--- a/doc/reference/libpurple/signals_jabber.xml Tue Oct 22 02:51:40 2013 +0530
+++ b/doc/reference/libpurple/signals_jabber.xml Tue Oct 22 02:52:36 2013 +0530
@@ -3,140 +3,301 @@
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<chapter id="chapter-signals-jabber">
- <title>Jabber signals</title>
+<title>Jabber signals</title>
- <programlisting>
- @signals
- @signal jabber-receiving-iq
- @signal jabber-receiving-message
- @signal jabber-receiving-presence
- @signal jabber-watched-iq
- @signal jabber-register-namespace-watcher
- @signal jabber-unregister-namespace-watcher
- @signal jabber-sending-xmlnode
- @signal jabber-receiving-xmlnode
- @endsignals
+<refsect1 id="jabber.signals" role="signal_proto">
+<title role="signal_proto.title">List of signals</title>
+<synopsis>
+ "<link linkend="jabber-jabber-receiving-iq">jabber-receiving-iq</link>"
+ "<link linkend="jabber-jabber-receiving-message">jabber-receiving-message</link>"
+ "<link linkend="jabber-jabber-receiving-presence">jabber-receiving-presence</link>"
+ "<link linkend="jabber-jabber-watched-iq">jabber-watched-iq</link>"
+ "<link linkend="jabber-jabber-register-namespace-watcher">jabber-register-namespace-watcher</link>"
+ "<link linkend="jabber-jabber-unregister-namespace-watcher">jabber-unregister-namespace-watcher</link>"
+ "<link linkend="jabber-jabber-sending-xmlnode">jabber-sending-xmlnode</link>"
+ "<link linkend="jabber-jabber-receiving-xmlnode">jabber-receiving-xmlnode</link>"
+</synopsis>
+</refsect1>
+
+<refsect1 id="jabber.signal-details" role="signals">
+<title role="signals.title">Signal details</title>
- @signaldef jabber-receiving-iq
- @signalproto
-gboolean (*iq_received)(PurpleConnection *gc, const char *type, const char *id,
- const char *from, PurpleXmlNode *iq);
- @endsignalproto
- @signaldesc
- Emitted when an XMPP IQ stanza is received. Allows a plugin to process IQ
- stanzas.
- @param gc The connection on which the stanza is received
- @param type The IQ type ('get', 'set', 'result', or 'error')
- @param id The ID attribute from the stanza. MUST NOT be NULL.
- @param from The originator of the stanza. MAY BE NULL if the stanza
- originated from the user's server.
- @param iq The full stanza received.
- @return TRUE if the plugin processed this stanza and *nobody else* should
- process it. FALSE otherwise.
- @endsignaldef
+<refsect2 id="jabber-jabber-receiving-iq" role="signal">
+ <title>The <literal>"jabber-receiving-iq"</literal> signal</title>
+ <programlisting>
+gboolean user_function (PurpleConnection *gc,
+ const char *type,
+ const char *id,
+ const char *from,
+ PurpleXmlNode *iq,
+ gpointer user_data)</programlisting>
+ <para>
+Emitted when an XMPP IQ stanza is received. Allows a plugin to process IQ stanzas.
+ </para>
+ <variablelist role="params">
+ <varlistentry>
+ <term><parameter>gc</parameter> :</term>
+ <listitem><simpara>The connection on which the stanza is received.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter> :</term>
+ <listitem><simpara>The IQ type ('get', 'set', 'result', or 'error').</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>id</parameter> :</term>
+ <listitem><simpara>The ID attribute from the stanza. MUST NOT be NULL.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>from</parameter> :</term>
+ <listitem><simpara>The originator of the stanza. MAY BE NULL if the stanza originated from the user's server.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>iq</parameter> :</term>
+ <listitem><simpara>The full stanza received.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>TRUE if the plugin processed this stanza and *nobody else* should process it. FALSE otherwise.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
- @signaldef jabber-receiving-message
- @signalproto
-gboolean (*message_received)(PurpleConnection *gc, const char *type,
- const char *id, const char *from, const char *to,
- PurpleXmlNode *message);
- @endsignalproto
- @signaldesc
- Emitted when an XMPP message stanza is received. Allows a plugin to
- process message stanzas.
- @param gc The connection on which the stanza is received
- @param type The message type (see rfc3921 or rfc3921bis)
- @param id The ID attribute from the stanza. MAY BE NULL.
- @param from The originator of the stanza. MAY BE NULL if the stanza
- originated from the user's server.
- @param to The destination of the stanza. This is probably either the
- full JID of the receiver or the receiver's bare JID.
- @param message The full stanza received.
- @return TRUE if the plugin processed this stanza and *nobody else* should
- process it. FALSE otherwise.
- @endsignaldef
+<refsect2 id="jabber-jabber-receiving-message" role="signal">
+ <title>The <literal>"jabber-receiving-message"</literal> signal</title>
+ <programlisting>
+gboolean user_function (PurpleConnection *gc,
+ const char *type,
+ const char *id,
+ const char *from,
+ const char *to,
+ PurpleXmlNode *message,
+ gpointer user_data)</programlisting>
+ <para>
+Emitted when an XMPP message stanza is received. Allows a plugin to process message stanzas.
+ </para>
+ <variablelist role="params">
+ <varlistentry>
+ <term><parameter>gc</parameter> :</term>
+ <listitem><simpara>The connection on which the stanza is received.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter> :</term>
+ <listitem><simpara>The message type (see rfc3921 or rfc3921bis).</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>id</parameter> :</term>
+ <listitem><simpara>The ID attribute from the stanza. MAY BE NULL.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>from</parameter> :</term>
+ <listitem><simpara>The originator of the stanza. MAY BE NULL if the stanza originated from the user's server.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>to</parameter> :</term>
+ <listitem><simpara>The destination of the stanza. This is probably either the full JID of the receiver or the receiver's bare JID.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>message</parameter> :</term>
+ <listitem><simpara>The full stanza received.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>TRUE if the plugin processed this stanza and *nobody else* should process it. FALSE otherwise.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
- @signaldef jabber-receiving-presence
- @signalproto
-gboolean (*presence_received)(PurpleConnection *gc, const char *type,
- const char *from, PurpleXmlNode *presence);
- @endsignalproto
- @signaldesc
- Emitted when an XMPP presence stanza is received. Allows a plugin to process
- presence stanzas.
- @param gc The connection on which the stanza is received
- @param type The presence type (see rfc3921 or rfc3921bis). NULL indicates
- this is an "available" (i.e. online) presence.
- @param from The originator of the stanza. MAY BE NULL if the stanza
- originated from the user's server.
- @param presence The full stanza received.
- @return TRUE if the plugin processed this stanza and *nobody else* should
- process it. FALSE otherwise.
- @endsignaldef
+<refsect2 id="jabber-jabber-receiving-presence" role="signal">
+ <title>The <literal>"jabber-receiving-presence"</literal> signal</title>
+ <programlisting>
+gboolean user_function (PurpleConnection *gc,
+ const char *type,
+ const char *from,
+ PurpleXmlNode *presence,
+ gpointer user_data)</programlisting>
+ <para>
+Emitted when an XMPP presence stanza is received. Allows a plugin to process presence stanzas.
+ </para>
+ <variablelist role="params">
+ <varlistentry>
+ <term><parameter>gc</parameter> :</term>
+ <listitem><simpara>The connection on which the stanza is received.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter> :</term>
+ <listitem><simpara>The presence type (see rfc3921 or rfc3921bis). NULL indicates this is an "available" (i.e. online) presence.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>from</parameter> :</term>
+ <listitem><simpara>The originator of the stanza. MAY BE NULL if the stanza originated from the user's server.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>presence</parameter> :</term>
+ <listitem><simpara>The full stanza received.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>TRUE if the plugin processed this stanza and *nobody else* should process it. FALSE otherwise.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
- @signaldef jabber-watched-iq
- @signalproto
-gboolean (*watched_iq)(PurpleConnection *gc, const char *type, const char *id,
- const char *from, PurpleXmlNode *child);
- @endsignalproto
- @signaldesc
- Emitted when an IQ with a watched (child, namespace) pair is received. See
- jabber-register-namespace-watcher and jabber-unregister-namespace-watcher.
- @param gc The connection on which the stanza is received
- @param type The IQ type ('get', 'set', 'result', or 'error')
- @param id The ID attribute from the stanza. MUST NOT be NULL.
- @param from The originator of the stanza. MAY BE NULL if the stanza
- originated from the user's server.
- @param child The child node with namespace.
- @return TRUE if the plugin processed this stanza and *nobody else* should
- process it. FALSE otherwise.
- @endsignaldef
+<refsect2 id="jabber-jabber-watched-iq" role="signal">
+ <title>The <literal>"jabber-watched-iq"</literal> signal</title>
+ <programlisting>
+gboolean user_function (PurpleConnection *gc,
+ const char *type,
+ const char *id,
+ const char *from,
+ PurpleXmlNode *child,
+ gpointer user_data)</programlisting>
+ <para>
+Emitted when an IQ with a watched (child, namespace) pair is received. See jabber-register-namespace-watcher and jabber-unregister-namespace-watcher.
+ </para>
+ <variablelist role="params">
+ <varlistentry>
+ <term><parameter>gc</parameter> :</term>
+ <listitem><simpara>The connection on which the stanza is received.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter> :</term>
+ <listitem><simpara>The IQ type ('get', 'set', 'result', or 'error').</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>id</parameter> :</term>
+ <listitem><simpara>The ID attribute from the stanza. MUST NOT be NULL.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>from</parameter> :</term>
+ <listitem><simpara>The originator of the stanza. MAY BE NULL if the stanza originated from the user's server.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>child</parameter> :</term>
+ <listitem><simpara>The child node with namespace.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>TRUE if the plugin processed this stanza and *nobody else* should process it. FALSE otherwise.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
- @signaldef jabber-register-namespace-watcher
- @signalproto
-void (register_namespace_watcher)(const char *node, const char *namespace);
- @endsignalproto
- @signaldesc
- Emit this signal to register your desire to have specific IQ stanzas to be
- emitted via the jabber-watched-iq signal when received.
- @param node The IQ child name to longer watch.
- @param namespace The IQ child namespace to longer watch.
- @endsignaldef
+<refsect2 id="jabber-jabber-register-namespace-watcher" role="signal">
+ <title>The <literal>"jabber-register-namespace-watcher"</literal> signal</title>
+ <programlisting>
+void user_function (const char *node,
+ const char *namespace,
+ gpointer user_data)</programlisting>
+ <para>
+Emit this signal to register your desire to have specific IQ stanzas to be emitted via the jabber-watched-iq signal when received.
+ </para>
+ <variablelist role="params">
+ <varlistentry>
+ <term><parameter>node</parameter> :</term>
+ <listitem><simpara>The IQ child name to longer watch.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>namespace</parameter> :</term>
+ <listitem><simpara>The IQ child namespace to longer watch.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
- @signaldef jabber-unregister-namespace-watcher
- @signalproto
-void (unregister_namespace_watcher)(const char *node, const char *namespace);
- @endsignalproto
- @signaldesc
- Emit this signal to unregister your desire to have specific IQ stanzas to be
- emitted via the jabber-watched-iq signal when received.
- @param node The IQ child name to no longer watch.
- @param namespace The IQ child namespace to no longer watch.
- @endsignaldef
+<refsect2 id="jabber-jabber-unregister-namespace-watcher" role="signal">
+ <title>The <literal>"jabber-unregister-namespace-watcher"</literal> signal</title>
+ <programlisting>
+void user_function (const char *node,
+ const char *namespace,
+ gpointer user_data)</programlisting>
+ <para>
+Emit this signal to unregister your desire to have specific IQ stanzas to be emitted via the jabber-watched-iq signal when received.
+ </para>
+ <variablelist role="params">
+ <varlistentry>
+ <term><parameter>node</parameter> :</term>
+ <listitem><simpara>The IQ child name to no longer watch.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>namespace</parameter> :</term>
+ <listitem><simpara>The IQ child namespace to no longer watch.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
- @signaldef jabber-sending-xmlnode
- @signalproto
-void (sending_xmlnode)(PurpleConnection *gc, PurpleXmlNode **stanza);
- @endsignalproto
- @signaldesc
- Emit this signal (@c purple_signal_emit) to send a stanza. It is preferred
- to use this instead of purple_protocol_server_iface_send_raw.
- @param gc The connection on which to send the stanza.
- @param stanza The stanza to send. If stanza is not NULL after being sent,
- the emitter should free it.
- @endsignaldef
+<refsect2 id="jabber-jabber-sending-xmlnode" role="signal">
+ <title>The <literal>"jabber-sending-xmlnode"</literal> signal</title>
+ <programlisting>
+void user_function (PurpleConnection *gc,
+ PurpleXmlNode **stanza,
+ gpointer user_data)</programlisting>
+ <para>
+Emit this signal (<literal>purple_signal_emit</literal>) to send a stanza. It is preferred to use this instead of purple_protocol_server_iface_send_raw.
+ </para>
+ <variablelist role="params">
+ <varlistentry>
+ <term><parameter>gc</parameter> :</term>
+ <listitem><simpara>The connection on which to send the stanza.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>stanza</parameter> :</term>
+ <listitem><simpara>The stanza to send. If stanza is not NULL after being sent, the emitter should free it.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
- @signaldef jabber-receiving-xmlnode
- @signalproto
-void (receiving_xmlnode)(PurpleConnection *gc, PurpleXmlNode **stanza);
- @endsignalproto
- @signaldesc
- Emitted when an XMPP stanza is received. Allows a plugin to process any
- stanza.
- @param gc The connection on which the stanza was received.
- @param stanza The received stanza. Set stanza to NULL (and free it) to
- stop processing the stanza.
- @endsignaldef
+<refsect2 id="jabber-jabber-receiving-xmlnode" role="signal">
+ <title>The <literal>"jabber-receiving-xmlnode"</literal> signal</title>
+ <programlisting>
+void user_function (PurpleConnection *gc,
+ PurpleXmlNode **stanza,
+ gpointer user_data)</programlisting>
+ <para>
+Emitted when an XMPP stanza is received. Allows a plugin to process any stanza.
+ </para>
+ <variablelist role="params">
+ <varlistentry>
+ <term><parameter>gc</parameter> :</term>
+ <listitem><simpara>The connection on which the stanza was received.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>stanza</parameter> :</term>
+ <listitem><simpara>The received stanza. Set stanza to NULL (and free it) to stop processing the stanza.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
- </programlisting>
+</refsect1>
+
</chapter>