doc/jabber-signals.dox

   1 /** @page jabber-signals Jabber Signals
   2
   3  @signals
   4   @signal jabber-receiving-iq
   5   @signal jabber-receiving-message
   6   @signal jabber-receiving-presence
   7   @signal jabber-watched-iq
   8   @signal jabber-register-namespace-watcher
   9   @signal jabber-unregister-namespace-watcher
  10   @signal jabber-sending-xmlnode
  11   @signal jabber-receiving-xmlnode
  12  @endsignals
  13
  14  <hr>
  15
  16  @signaldef jabber-receiving-iq
  17   @signalproto
  18 gboolean (*iq_received)(PurpleConnection *gc, const char *type, const char *id,
  19                      const char *from, xmlnode *iq);
  20   @endsignalproto
  21   @signaldesc
  22    Emitted when an XMPP IQ stanza is received. Allows a plugin to process IQ
  23    stanzas.
  24   @param gc        The connection on which the stanza is received
  25   @param type      The IQ type ('get', 'set', 'result', or 'error')
  26   @param id        The ID attribute from the stanza. MUST NOT be NULL.
  27   @param from      The originator of the stanza. MAY BE NULL if the stanza
  28                    originated from the user's server.
  29   @param iq        The full stanza received.
  30   @return TRUE if the plugin processed this stanza and *nobody else* should
  31           process it. FALSE otherwise.
  32  @endsignaldef
  33
  34  @signaldef jabber-receiving-message
  35   @signalproto
  36 gboolean (*message_received)(PurpleConnection *gc, const char *type,
  37                               const char *id, const char *from, const char *to,
  38                               xmlnode *message);
  39   @endsignalproto
  40   @signaldesc
  41    Emitted when an XMPP message stanza is received. Allows a plugin to
  42    process message stanzas.
  43   @param gc        The connection on which the stanza is received
  44   @param type      The message type (see rfc3921 or rfc3921bis)
  45   @param id        The ID attribute from the stanza. MAY BE NULL.
  46   @param from      The originator of the stanza. MAY BE NULL if the stanza
  47                    originated from the user's server.
  48   @param to        The destination of the stanza. This is probably either the
  49                    full JID of the receiver or the receiver's bare JID.
  50   @param message   The full stanza received.
  51   @return TRUE if the plugin processed this stanza and *nobody else* should
  52           process it. FALSE otherwise.
  53  @endsignaldef
  54
  55  @signaldef jabber-receiving-presence
  56   @signalproto
  57 gboolean (*presence_received)(PurpleConnection *gc, const char *type,
  58                                const char *from, xmlnode *presence);
  59   @endsignalproto
  60   @signaldesc
  61    Emitted when an XMPP presence stanza is received. Allows a plugin to process
  62    presence stanzas.
  63   @param gc        The connection on which the stanza is received
  64   @param type      The presence type (see rfc3921 or rfc3921bis). NULL indicates
  65                    this is an "available" (i.e. online) presence.
  66   @param from      The originator of the stanza. MAY BE NULL if the stanza
  67                    originated from the user's server.
  68   @param presence  The full stanza received.
  69   @return TRUE if the plugin processed this stanza and *nobody else* should
  70           process it. FALSE otherwise.
  71  @endsignaldef
  72
  73  @signaldef jabber-watched-iq
  74   @signalproto
  75 gboolean (*watched_iq)(PurpleConnection *gc, const char *type, const char *id,
  76                        const char *from, xmlnode *child);
  77   @endsignalproto
  78   @signaldesc
  79    Emitted when an IQ with a watched (child, namespace) pair is received.  See
  80    jabber-register-namespace-watcher and jabber-unregister-namespace-watcher.
  81   @param gc        The connection on which the stanza is received
  82   @param type      The IQ type ('get', 'set', 'result', or 'error')
  83   @param id        The ID attribute from the stanza. MUST NOT be NULL.
  84   @param from      The originator of the stanza. MAY BE NULL if the stanza
  85                    originated from the user's server.
  86   @param child     The child node with namespace.
  87   @return TRUE if the plugin processed this stanza and *nobody else* should
  88           process it. FALSE otherwise.
  89  @endsignaldef
  90
  91  @signaldef jabber-register-namespace-watcher
  92   @signalproto
  93 void (register_namespace_watcher)(const char *node, const char *namespace);
  94   @endsignalproto
  95   @signaldesc
  96    Emit this signal to register your desire to have specific IQ stanzas to be
  97    emitted via the jabber-watched-iq signal when received.
  98   @param node      The IQ child name to longer watch.
  99   @param namespace The IQ child namespace to longer watch.
 100  @endsignaldef
 101
 102  @signaldef jabber-unregister-namespace-watcher
 103   @signalproto
 104 void (unregister_namespace_watcher)(const char *node, const char *namespace);
 105   @endsignalproto
 106   @signaldesc
 107    Emit this signal to unregister your desire to have specific IQ stanzas to be
 108    emitted via the jabber-watched-iq signal when received.
 109   @param node      The IQ child name to no longer watch.
 110   @param namespace The IQ child namespace to no longer watch.
 111  @endsignaldef
 112
 113  @signaldef jabber-sending-xmlnode
 114   @signalproto
 115 void (sending_xmlnode)(PurpleConnection *gc, xmlnode **stanza);
 116   @endsignalproto
 117   @signaldesc
 118    Emit this signal (@c purple_signal_emit) to send a stanza. It is preferred
 119    to use this instead of prpl_info->send_raw.
 120    @param gc      The connection on which to send the stanza.
 121    @param stanza  The stanza to send. If stanza is not NULL after being sent,
 122                   the emitter should free it.
 123  @endsignaldef
 124
 125  @signaldef jabber-receiving-xmlnode
 126   @signalproto
 127 void (receiving_xmlnode)(PurpleConnection *gc, xmlnode **stanza);
 128   @endsignalproto
 129   @signaldesc
 130    Emitted when an XMPP stanza is received. Allows a plugin to process any
 131    stanza.
 132    @param gc     The connection on which the stanza was received.
 133    @param stanza The received stanza. Set stanza to NULL (and free it) to
 134                  stop processing the stanza.
 135  @endsignaldef
 136
 137 */
 138 // vim: syntax=c.doxygen tw=75 et