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 #ifndef PURPLE_JABBER_IQ_H_
  25 #define PURPLE_JABBER_IQ_H_
  26
  27 typedef enum {
  28         JABBER_IQ_SET,
  29         JABBER_IQ_GET,
  30         JABBER_IQ_RESULT,
  31         JABBER_IQ_ERROR,
  32         JABBER_IQ_NONE
  33 } JabberIqType;
  34
  35 #include "jabber.h"
  36 #include "connection.h"
  37
  38 typedef struct _JabberIq JabberIq;
  39 typedef struct _JabberIqCallbackData  JabberIqCallbackData;
  40
  41 /**
  42  * A JabberIqHandler is called to process an incoming IQ stanza.
  43  * Handlers typically process unsolicited incoming GETs or SETs for their
  44  * registered namespace, but may be called to handle the results of a
  45  * GET or SET that we generated if no JabberIqCallback was generated
  46  * The handler may be called for the results of a GET or SET (RESULT or ERROR)
  47  * that we generated
  48  * if the generating function did not register a JabberIqCallback.
  49  *
  50  * @param js    The JabberStream object.
  51  * @param from  The remote entity (the from attribute on the <iq/> stanza)
  52  * @param type  The IQ type.
  53  * @param id    The IQ id (the id attribute on the <iq/> stanza)
  54  * @param child The child element of the <iq/> stanza that matches the name
  55  *              and namespace registered with jabber_iq_register_handler.
  56  *
  57  * @see jabber_iq_register_handler()
  58  * @see JabberIqCallback
  59  */
  60 typedef void (JabberIqHandler)(JabberStream *js, const char *from,
  61                                JabberIqType type, const char *id,
  62                                PurpleXmlNode *child);
  63
  64 /**
  65  * A JabberIqCallback is called to process the results of a GET or SET that
  66  * we send to a remote entity. The callback is matched based on the id
  67  * of the incoming stanza (which matches the one on the initial stanza).
  68  *
  69  * @param js     The JabberStream object.
  70  * @param from   The remote entity (the from attribute on the <iq/> stanza)
  71  * @param type   The IQ type. The only possible values are JABBER_IQ_RESULT
  72  *               and JABBER_IQ_ERROR.
  73  * @param id     The IQ id (the id attribute on the <iq/> stanza)
  74  * @param packet The <iq/> stanza
  75  * @param data   The callback data passed to jabber_iq_set_callback()
  76  *
  77  * @see jabber_iq_set_callback()
  78  */
  79 typedef void (JabberIqCallback)(JabberStream *js, const char *from,
  80                                 JabberIqType type, const char *id,
  81                                 PurpleXmlNode *packet, gpointer data);
  82
  83 struct _JabberIq {
  84         JabberIqType type;
  85         char *id;
  86         PurpleXmlNode *node;
  87
  88         JabberIqCallback *callback;
  89         gpointer callback_data;
  90
  91         JabberStream *js;
  92 };
  93
  94 JabberIq *jabber_iq_new(JabberStream *js, JabberIqType type);
  95 JabberIq *jabber_iq_new_query(JabberStream *js, JabberIqType type,
  96                 const char *xmlns);
  97
  98 void jabber_iq_parse(JabberStream *js, PurpleXmlNode *packet);
  99
 100 void jabber_iq_callbackdata_free(JabberIqCallbackData *jcd);
 101 void jabber_iq_remove_callback_by_id(JabberStream *js, const char *id);
 102 void jabber_iq_set_callback(JabberIq *iq, JabberIqCallback *cb, gpointer data);
 103 void jabber_iq_set_id(JabberIq *iq, const char *id);
 104
 105 void jabber_iq_send(JabberIq *iq);
 106 void jabber_iq_free(JabberIq *iq);
 107
 108 void jabber_iq_init(void);
 109 void jabber_iq_uninit(void);
 110
 111 void jabber_iq_register_handler(const char *node, const char *xmlns,
 112                                 JabberIqHandler *func);
 113
 114 /* Connected to namespace-handler registration signals */
 115 void jabber_iq_signal_register(const gchar *node, const gchar *xmlns);
 116 void jabber_iq_signal_unregister(const gchar *node, const gchar *xmlns);
 117
 118 #endif /* PURPLE_JABBER_IQ_H_ */