libpurple/protocols/jabber/iq.h

   1 /**
   2  * @file iq.h JabberID handlers
   3  *
   4  * purple
   5  *
   6  * Purple is the legal property of its developers, whose names are too numerous
   7  * to list here.  Please refer to the COPYRIGHT file distributed with this
   8  * source distribution.
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  23  */
  24
  25 #ifndef PURPLE_JABBER_IQ_H
  26 #define PURPLE_JABBER_IQ_H
  27
  28 typedef enum {
  29         JABBER_IQ_SET,
  30         JABBER_IQ_GET,
  31         JABBER_IQ_RESULT,
  32         JABBER_IQ_ERROR,
  33         JABBER_IQ_NONE
  34 } JabberIqType;
  35
  36 #include "jabber.h"
  37 #include "connection.h"
  38
  39 typedef struct _JabberIq JabberIq;
  40 typedef struct _JabberIqCallbackData  JabberIqCallbackData;
  41
  42 /**
  43  * A JabberIqHandler is called to process an incoming IQ stanza.
  44  * Handlers typically process unsolicited incoming GETs or SETs for their
  45  * registered namespace, but may be called to handle the results of a
  46  * GET or SET that we generated if no JabberIqCallback was generated
  47  * The handler may be called for the results of a GET or SET (RESULT or ERROR)
  48  * that we generated
  49  * if the generating function did not register a JabberIqCallback.
  50  *
  51  * @param js    The JabberStream object.
  52  * @param from  The remote entity (the from attribute on the <iq/> stanza)
  53  * @param type  The IQ type.
  54  * @param id    The IQ id (the id attribute on the <iq/> stanza)
  55  * @param child The child element of the <iq/> stanza that matches the name
  56  *              and namespace registered with jabber_iq_register_handler.
  57  *
  58  * @see jabber_iq_register_handler()
  59  * @see JabberIqCallback
  60  */
  61 typedef void (JabberIqHandler)(JabberStream *js, const char *from,
  62                                JabberIqType type, const char *id,
  63                                PurpleXmlNode *child);
  64
  65 /**
  66  * A JabberIqCallback is called to process the results of a GET or SET that
  67  * we send to a remote entity. The callback is matched based on the id
  68  * of the incoming stanza (which matches the one on the initial stanza).
  69  *
  70  * @param js     The JabberStream object.
  71  * @param from   The remote entity (the from attribute on the <iq/> stanza)
  72  * @param type   The IQ type. The only possible values are JABBER_IQ_RESULT
  73  *               and JABBER_IQ_ERROR.
  74  * @param id     The IQ id (the id attribute on the <iq/> stanza)
  75  * @param packet The <iq/> stanza
  76  * @param data   The callback data passed to jabber_iq_set_callback()
  77  *
  78  * @see jabber_iq_set_callback()
  79  */
  80 typedef void (JabberIqCallback)(JabberStream *js, const char *from,
  81                                 JabberIqType type, const char *id,
  82                                 PurpleXmlNode *packet, gpointer data);
  83
  84 struct _JabberIq {
  85         JabberIqType type;
  86         char *id;
  87         PurpleXmlNode *node;
  88
  89         JabberIqCallback *callback;
  90         gpointer callback_data;
  91
  92         JabberStream *js;
  93 };
  94
  95 JabberIq *jabber_iq_new(JabberStream *js, JabberIqType type);
  96 JabberIq *jabber_iq_new_query(JabberStream *js, JabberIqType type,
  97                 const char *xmlns);
  98
  99 void jabber_iq_parse(JabberStream *js, PurpleXmlNode *packet);
 100
 101 void jabber_iq_callbackdata_free(JabberIqCallbackData *jcd);
 102 void jabber_iq_remove_callback_by_id(JabberStream *js, const char *id);
 103 void jabber_iq_set_callback(JabberIq *iq, JabberIqCallback *cb, gpointer data);
 104 void jabber_iq_set_id(JabberIq *iq, const char *id);
 105
 106 void jabber_iq_send(JabberIq *iq);
 107 void jabber_iq_free(JabberIq *iq);
 108
 109 void jabber_iq_init(void);
 110 void jabber_iq_uninit(void);
 111
 112 void jabber_iq_register_handler(const char *node, const char *xmlns,
 113                                 JabberIqHandler *func);
 114
 115 /* Connected to namespace-handler registration signals */
 116 void jabber_iq_signal_register(const gchar *node, const gchar *xmlns);
 117 void jabber_iq_signal_unregister(const gchar *node, const gchar *xmlns);
 118
 119 #endif /* PURPLE_JABBER_IQ_H */