libpurple/protocols/jabber/pep.h

   1 /*
   2  * purple - Jabber Protocol Plugin
   3  *
   4  * Purple is the legal property of its developers, whose names are too numerous
   5  * to list here.  Please refer to the COPYRIGHT file distributed with this
   6  * source distribution.
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  21  *
  22  */
  23
  24 #ifndef PURPLE_JABBER_PEP_H_
  25 #define PURPLE_JABBER_PEP_H_
  26
  27 #include "jabber.h"
  28 #include "message.h"
  29 #include "buddy.h"
  30
  31 void jabber_pep_init(void);
  32 void jabber_pep_uninit(void);
  33
  34 void jabber_pep_init_actions(GList **m);
  35
  36 /*
  37  * Callback for receiving PEP events.
  38  *
  39  * @parameter js        The JabberStream this item was received on
  40  * @parameter items     The &lt;items/>-tag with the &lt;item/>-children
  41  */
  42 typedef void (JabberPEPHandler)(JabberStream *js, const char *from, PurpleXmlNode *items);
  43
  44 /*
  45  * Registers a callback for PEP events. Also automatically announces this receiving capability via disco#info.
  46  * Don't forget to use jabber_add_feature when supporting the sending of PEP events of this type.
  47  *
  48  * @parameter xmlns                     The namespace for this event
  49  * @parameter handlerfunc       The callback to be used when receiving an event with this namespace
  50  */
  51 void jabber_pep_register_handler(const char *xmlns, JabberPEPHandler handlerfunc);
  52
  53 /*
  54  * Request a specific item from another PEP node.
  55  *
  56  * @parameter js        The JabberStream that should be used
  57  * @parameter to        The target PEP node
  58  * @parameter node      The node name of the item that is requested
  59  * @parameter id        The item id of the requested item (may be NULL)
  60  * @parameter cb        The callback to be used when this item is received
  61  *
  62  * The items element passed to the callback will be NULL if any error occurred (like a permission error, node doesn't exist etc.)
  63  */
  64 void jabber_pep_request_item(JabberStream *js, const char *to, const char *node, const char *id, JabberPEPHandler cb);
  65
  66 /*
  67  * Default callback that can be used for namespaces which should only be enabled when PEP is supported
  68  *
  69  * @parameter js                The JabberStream struct for this connection
  70  * @parameter namespace The namespace that's queried, ignored.
  71  *
  72  * @returns TRUE when PEP is enabled, FALSE otherwise
  73  */
  74 gboolean jabber_pep_namespace_only_when_pep_enabled_cb(JabberStream *js, const gchar *namespace);
  75
  76 void jabber_handle_event(JabberMessage *jm);
  77
  78 /**
  79  * Delete the specified PEP node.
  80  */
  81 void jabber_pep_delete_node(JabberStream *js, const gchar *node);
  82
  83 /*
  84  * Publishes PEP item(s)
  85  *
  86  * @parameter js        The JabberStream associated with the connection this event should be published
  87  * @parameter publish   The publish node. This could be for example &lt;publish node='http://jabber.org/protocol/tune'/> with an &lt;item/> as subnode
  88  */
  89 void jabber_pep_publish(JabberStream *js, PurpleXmlNode *publish);
  90
  91 #endif /* PURPLE_JABBER_PEP_H_ */