1f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch/* 2f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * libjingle 3f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * Copyright 2004--2005, Google Inc. 4f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * 5f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * Redistribution and use in source and binary forms, with or without 6f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * modification, are permitted provided that the following conditions are met: 7f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * 8f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * 1. Redistributions of source code must retain the above copyright notice, 9f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * this list of conditions and the following disclaimer. 10f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * 2. Redistributions in binary form must reproduce the above copyright notice, 11f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * this list of conditions and the following disclaimer in the documentation 12f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * and/or other materials provided with the distribution. 13f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * 3. The name of the author may not be used to endorse or promote products 14f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * derived from this software without specific prior written permission. 15f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * 16f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 17f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 19f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 20f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 21f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 22f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 23f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 24f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 25f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch */ 27f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 28f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#ifndef _xmppengine_h_ 29f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#define _xmppengine_h_ 30f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 31f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch// also part of the API 32f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#include "talk/xmpp/jid.h" 33f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#include "talk/xmllite/qname.h" 34f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#include "talk/xmllite/xmlelement.h" 35f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 36f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 37f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochnamespace buzz { 38f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 39f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochclass XmppEngine; 40f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochclass SaslHandler; 41f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochtypedef void * XmppIqCookie; 42f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 43f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! XMPP stanza error codes. 44f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Used in XmppEngine.SendStanzaError(). 45f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochenum XmppStanzaError { 46f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_BAD_REQUEST, 47f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_CONFLICT, 48f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_FEATURE_NOT_IMPLEMENTED, 49f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_FORBIDDEN, 50f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_GONE, 51f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_INTERNAL_SERVER_ERROR, 52f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_ITEM_NOT_FOUND, 53f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_JID_MALFORMED, 54f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_NOT_ACCEPTABLE, 55f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_NOT_ALLOWED, 56f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_PAYMENT_REQUIRED, 57f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_RECIPIENT_UNAVAILABLE, 58f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_REDIRECT, 59f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_REGISTRATION_REQUIRED, 60f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_SERVER_NOT_FOUND, 61f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_SERVER_TIMEOUT, 62f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_RESOURCE_CONSTRAINT, 63f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_SERVICE_UNAVAILABLE, 64f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_SUBSCRIPTION_REQUIRED, 65f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_UNDEFINED_CONDITION, 66f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XSE_UNEXPECTED_REQUEST, 67f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch}; 68f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 69f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch// XmppReturnStatus 70f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch// This is used by API functions to synchronously return status. 71f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochenum XmppReturnStatus { 72f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XMPP_RETURN_OK, 73f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XMPP_RETURN_BADARGUMENT, 74f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XMPP_RETURN_BADSTATE, 75f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XMPP_RETURN_PENDING, 76f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XMPP_RETURN_UNEXPECTED, 77f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XMPP_RETURN_NOTYETIMPLEMENTED, 78f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch}; 79f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 80f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Callback for socket output for an XmppEngine connection. 81f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Register via XmppEngine.SetOutputHandler. An XmppEngine 82f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! can call back to this handler while it is processing 83f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Connect, SendStanza, SendIq, Disconnect, or HandleInput. 84f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochclass XmppOutputHandler { 85f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochpublic: 86f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual ~XmppOutputHandler() {} 87f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 88f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Deliver the specified bytes to the XMPP socket. 89f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual void WriteOutput(const char * bytes, size_t len) = 0; 90f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 91f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Initiate TLS encryption on the socket. 92f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! The implementation must verify that the SSL 93f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! certificate matches the given domainname. 94f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual void StartTls(const std::string & domainname) = 0; 95f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 96f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Called when engine wants the connecton closed. 97f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual void CloseConnection() = 0; 98f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch}; 99f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 100f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Callback to deliver engine state change notifications 101f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! to the object managing the engine. 102f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochclass XmppSessionHandler { 103f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochpublic: 104f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual ~XmppSessionHandler() {} 105f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Called when engine changes state. Argument is new state. 106f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual void OnStateChange(int state) = 0; 107f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch}; 108f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 109f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Callback to deliver stanzas to an Xmpp application module. 110f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Register via XmppEngine.SetDefaultSessionHandler or via 111f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! XmppEngine.AddSessionHAndler. 112f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochclass XmppStanzaHandler { 113f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochpublic: 114f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual ~XmppStanzaHandler() {} 115f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Process the given stanza. 116f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! The handler must return true if it has handled the stanza. 117f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! A false return value causes the stanza to be passed on to 118f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! the next registered handler. 119f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual bool HandleStanza(const XmlElement * stanza) = 0; 120f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch}; 121f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 122f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Callback to deliver iq responses (results and errors). 123f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Register while sending an iq via XmppEngine.SendIq. 124f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! Iq responses are routed to matching XmppIqHandlers in preference 125f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! to sending to any registered SessionHandlers. 126f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochclass XmppIqHandler { 127f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochpublic: 128f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual ~XmppIqHandler() {} 129f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Called to handle the iq response. 130f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! The response may be either a result or an error, and will have 131f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! an 'id' that matches the request and a 'from' that matches the 132f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! 'to' of the request. Called no more than once; once this is 133f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! called, the handler is automatically unregistered. 134f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual void IqResponse(XmppIqCookie cookie, const XmlElement * pelStanza) = 0; 135f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch}; 136f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 137f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! The XMPP connection engine. 138f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! This engine implements the client side of the 'core' XMPP protocol. 139f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! To use it, register an XmppOutputHandler to handle socket output 140f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! and pass socket input to HandleInput. Then application code can 141f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! set up the connection with a user, password, and other settings, 142f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! and then call Connect() to initiate the connection. 143f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! An application can listen for events and receive stanzas by 144f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch//! registering an XmppStanzaHandler via AddStanzaHandler(). 145f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochclass XmppEngine { 146f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdochpublic: 147f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch static XmppEngine * Create(); 148f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual ~XmppEngine() {} 149f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 150f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Error codes. See GetError(). 151f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch enum Error { 152f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_NONE = 0, //!< No error 153f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_XML, //!< Malformed XML or encoding error 154f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_STREAM, //!< XMPP stream error - see GetStreamError() 155f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_VERSION, //!< XMPP version error 156f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_UNAUTHORIZED, //!< User is not authorized (rejected credentials) 157f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_TLS, //!< TLS could not be negotiated 158f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_AUTH, //!< Authentication could not be negotiated 159f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_BIND, //!< Resource or session binding could not be negotiated 160f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_CONNECTION_CLOSED,//!< Connection closed by output handler. 161f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_DOCUMENT_CLOSED, //!< Closed by </stream:stream> 162f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_SOCKET, //!< Socket error 163f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_NETWORK_TIMEOUT, //!< Some sort of timeout (eg., we never got the roster) 164f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ERROR_MISSING_USERNAME //!< User has a Google Account but no nickname 165f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch }; 166f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 167f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! States. See GetState(). 168f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch enum State { 169f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch STATE_NONE = 0, //!< Nonexistent state 170f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch STATE_START, //!< Initial state. 171f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch STATE_OPENING, //!< Exchanging stream headers, authenticating and so on. 172f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch STATE_OPEN, //!< Authenticated and bound. 173f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch STATE_CLOSED, //!< Session closed, possibly due to error. 174f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch }; 175f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 176f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch // SOCKET INPUT AND OUTPUT ------------------------------------------------ 177f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 178f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Registers the handler for socket output 179f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SetOutputHandler(XmppOutputHandler *pxoh) = 0; 180f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 181f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Provides socket input to the engine 182f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus HandleInput(const char * bytes, size_t len) = 0; 183f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 184f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Advises the engine that the socket has closed 185f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus ConnectionClosed(int subcode) = 0; 186f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 187f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch // SESSION SETUP --------------------------------------------------------- 188f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 189f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Indicates the (bare) JID for the user to use. 190f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SetUser(const Jid & jid)= 0; 191f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 192f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Get the login (bare) JID. 193f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual const Jid & GetUser() = 0; 194f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 195f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Provides different methods for credentials for login. 196f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Takes ownership of this object; deletes when login is done 197f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SetSaslHandler(SaslHandler * h) = 0; 198f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 199f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Sets whether TLS will be used within the connection (default true). 200f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SetUseTls(bool useTls) = 0; 201f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 202f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Sets an alternate domain from which we allows TLS certificates. 203f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! This is for use in the case where a we want to allow a proxy to 204f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! serve up its own certificate rather than one owned by the underlying 205f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! domain. 206f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SetTlsServer(const std::string & proxy_hostname, 207f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch const std::string & proxy_domain) = 0; 208f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 209f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Gets whether TLS will be used within the connection. 210f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual bool GetUseTls() = 0; 211f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 212f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Sets the request resource name, if any (optional). 213f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Note that the resource name may be overridden by the server; after 214f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! binding, the actual resource name is available as part of FullJid(). 215f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SetRequestedResource(const std::string& resource) = 0; 216f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 217f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Gets the request resource name. 218f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual const std::string & GetRequestedResource() = 0; 219f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 220f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Sets language 221f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual void SetLanguage(const std::string & lang) = 0; 222f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 223f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch // SESSION MANAGEMENT --------------------------------------------------- 224f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 225f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Set callback for state changes. 226f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SetSessionHandler(XmppSessionHandler* handler) = 0; 227f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 228f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Initiates the XMPP connection. 229f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! After supplying connection settings, call this once to initiate, 230f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! (optionally) encrypt, authenticate, and bind the connection. 231f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus Connect() = 0; 232f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 233f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! The current engine state. 234f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual State GetState() = 0; 235f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 236f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Returns true if the connection is encrypted (under TLS) 237f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual bool IsEncrypted() = 0; 238f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 239f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! The error code. 240f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Consult this after XmppOutputHandler.OnClose(). 241f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual Error GetError(int *subcode) = 0; 242f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 243f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! The stream:error stanza, when the error is XmppEngine::ERROR_STREAM. 244f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Notice the stanza returned is owned by the XmppEngine and 245f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! is deleted when the engine is destroyed. 246f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual const XmlElement * GetStreamError() = 0; 247f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 248f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Closes down the connection. 249f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Sends CloseConnection to output, and disconnects and registered 250f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! session handlers. After Disconnect completes, it is guaranteed 251f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! that no further callbacks will be made. 252f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus Disconnect() = 0; 253f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 254f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch // APPLICATION USE ------------------------------------------------------- 255f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 256f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch enum HandlerLevel { 257f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch HL_NONE = 0, 258f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch HL_PEEK, //!< Sees messages before all other processing; cannot abort 259f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch HL_SINGLE, //!< Watches for a single message, e.g., by id and sender 260f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch HL_SENDER, //!< Watches for a type of message from a specific sender 261f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch HL_TYPE, //!< Watches a type of message, e.g., all groupchat msgs 262f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch HL_ALL, //!< Watches all messages - gets last shot 263f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch HL_COUNT, //!< Count of handler levels 264f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch }; 265f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 266f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Adds a listener for session events. 267f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Stanza delivery is chained to session handlers; the first to 268f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! return 'true' is the last to get each stanza. 269f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus AddStanzaHandler(XmppStanzaHandler* handler, HandlerLevel level = HL_PEEK) = 0; 270f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 271f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Removes a listener for session events. 272f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus RemoveStanzaHandler(XmppStanzaHandler* handler) = 0; 273f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 274f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Sends a stanza to the server. 275f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SendStanza(const XmlElement * pelStanza) = 0; 276f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 277f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Sends raw text to the server 278f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SendRaw(const std::string & text) = 0; 279f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 280f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Sends an iq to the server, and registers a callback for the result. 281f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Returns the cookie passed to the result handler. 282f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SendIq(const XmlElement* pelStanza, 283f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XmppIqHandler* iq_handler, 284f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XmppIqCookie* cookie) = 0; 285f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 286f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Unregisters an iq callback handler given its cookie. 287f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! No callback will come to this handler after it's unregistered. 288f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus RemoveIqHandler(XmppIqCookie cookie, 289f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XmppIqHandler** iq_handler) = 0; 290f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 291f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 292f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Forms and sends an error in response to the given stanza. 293f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Swaps to and from, sets type to "error", and adds error information 294f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! based on the passed code. Text is optional and may be STR_EMPTY. 295f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual XmppReturnStatus SendStanzaError(const XmlElement * pelOriginal, 296f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch XmppStanzaError code, 297f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch const std::string & text) = 0; 298f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 299f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! The fullly bound JID. 300f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! This JID is only valid after binding has succeeded. If the value 301f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! is JID_NULL, the binding has not succeeded. 302f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual const Jid & FullJid() = 0; 303f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 304f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! The next unused iq id for this connection. 305f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! Call this when building iq stanzas, to ensure that each iq 306f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch //! gets its own unique id. 307f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch virtual std::string NextId() = 0; 308f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 309f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch}; 310f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 311f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch} 312f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 313f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 314f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch// Move these to a better location 315f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 316f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#define XMPP_FAILED(x) \ 317f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ( (x) == buzz::XMPP_RETURN_OK ? false : true) \ 318f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 319f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 320f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#define XMPP_SUCCEEDED(x) \ 321f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch ( (x) == buzz::XMPP_RETURN_OK ? true : false) \ 322f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 323f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#define IFR(x) \ 324f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch do { \ 325f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch xmpp_status = (x); \ 326f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch if (XMPP_FAILED(xmpp_status)) { \ 327f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch return xmpp_status; \ 328f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch } \ 329f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch } while (false) \ 330f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 331f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 332f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#define IFC(x) \ 333f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch do { \ 334f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch xmpp_status = (x); \ 335f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch if (XMPP_FAILED(xmpp_status)) { \ 336f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch goto Cleanup; \ 337f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch } \ 338f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch } while (false) \ 339f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 340f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch 341f74420b3285b9fe04a7e00aa3b8c0ab07ea344bcBen Murdoch#endif 342