blob: 7a1b21bcbe502b33909bb082d36b661414a0fa09 [file] [log] [blame]
* Copyright 2004 The WebRTC Project Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
// also part of the API
#include "third_party/libjingle_xmpp/xmllite/qname.h"
#include "third_party/libjingle_xmpp/xmllite/xmlelement.h"
#include "third_party/libjingle_xmpp/xmpp/jid.h"
namespace jingle_xmpp {
class XmppEngine;
class SaslHandler;
typedef void * XmppIqCookie;
//! XMPP stanza error codes.
//! Used in XmppEngine.SendStanzaError().
enum XmppStanzaError {
// XmppReturnStatus
// This is used by API functions to synchronously return status.
enum XmppReturnStatus {
// TlsOptions
// This is used by API to identify TLS setting.
enum TlsOptions {
//! Callback for socket output for an XmppEngine connection.
//! Register via XmppEngine.SetOutputHandler. An XmppEngine
//! can call back to this handler while it is processing
//! Connect, SendStanza, SendIq, Disconnect, or HandleInput.
class XmppOutputHandler {
virtual ~XmppOutputHandler() {}
//! Deliver the specified bytes to the XMPP socket.
virtual void WriteOutput(const char * bytes, size_t len) = 0;
//! Initiate TLS encryption on the socket.
//! The implementation must verify that the SSL
//! certificate matches the given domainname.
virtual void StartTls(const std::string & domainname) = 0;
//! Called when engine wants the connecton closed.
virtual void CloseConnection() = 0;
//! Callback to deliver engine state change notifications
//! to the object managing the engine.
class XmppSessionHandler {
virtual ~XmppSessionHandler() {}
//! Called when engine changes state. Argument is new state.
virtual void OnStateChange(int state) = 0;
//! Callback to deliver stanzas to an Xmpp application module.
//! Register via XmppEngine.SetDefaultSessionHandler or via
//! XmppEngine.AddSessionHAndler.
class XmppStanzaHandler {
virtual ~XmppStanzaHandler() {}
//! Process the given stanza.
//! The handler must return true if it has handled the stanza.
//! A false return value causes the stanza to be passed on to
//! the next registered handler.
virtual bool HandleStanza(const XmlElement * stanza) = 0;
//! Callback to deliver iq responses (results and errors).
//! Register while sending an iq via XmppEngine.SendIq.
//! Iq responses are routed to matching XmppIqHandlers in preference
//! to sending to any registered SessionHandlers.
class XmppIqHandler {
virtual ~XmppIqHandler() {}
//! Called to handle the iq response.
//! The response may be either a result or an error, and will have
//! an 'id' that matches the request and a 'from' that matches the
//! 'to' of the request. Called no more than once; once this is
//! called, the handler is automatically unregistered.
virtual void IqResponse(XmppIqCookie cookie, const XmlElement * pelStanza) = 0;
//! The XMPP connection engine.
//! This engine implements the client side of the 'core' XMPP protocol.
//! To use it, register an XmppOutputHandler to handle socket output
//! and pass socket input to HandleInput. Then application code can
//! set up the connection with a user, password, and other settings,
//! and then call Connect() to initiate the connection.
//! An application can listen for events and receive stanzas by
//! registering an XmppStanzaHandler via AddStanzaHandler().
class XmppEngine {
static XmppEngine * Create();
virtual ~XmppEngine() {}
//! Error codes. See GetError().
enum Error {
ERROR_NONE = 0, //!< No error
ERROR_XML, //!< Malformed XML or encoding error
ERROR_STREAM, //!< XMPP stream error - see GetStreamError()
ERROR_VERSION, //!< XMPP version error
ERROR_UNAUTHORIZED, //!< User is not authorized (rejected credentials)
ERROR_TLS, //!< TLS could not be negotiated
ERROR_AUTH, //!< Authentication could not be negotiated
ERROR_BIND, //!< Resource or session binding could not be negotiated
ERROR_CONNECTION_CLOSED,//!< Connection closed by output handler.
ERROR_DOCUMENT_CLOSED, //!< Closed by </stream:stream>
ERROR_SOCKET, //!< Socket error
ERROR_NETWORK_TIMEOUT, //!< Some sort of timeout (eg., we never got the roster)
ERROR_MISSING_USERNAME //!< User has a Google Account but no nickname
//! States. See GetState().
enum State {
STATE_NONE = 0, //!< Nonexistent state
STATE_START, //!< Initial state.
STATE_OPENING, //!< Exchanging stream headers, authenticating and so on.
STATE_OPEN, //!< Authenticated and bound.
STATE_CLOSED, //!< Session closed, possibly due to error.
// SOCKET INPUT AND OUTPUT ------------------------------------------------
//! Registers the handler for socket output
virtual XmppReturnStatus SetOutputHandler(XmppOutputHandler *pxoh) = 0;
//! Provides socket input to the engine
virtual XmppReturnStatus HandleInput(const char * bytes, size_t len) = 0;
//! Advises the engine that the socket has closed
virtual XmppReturnStatus ConnectionClosed(int subcode) = 0;
// SESSION SETUP ---------------------------------------------------------
//! Indicates the (bare) JID for the user to use.
virtual XmppReturnStatus SetUser(const Jid & jid)= 0;
//! Get the login (bare) JID.
virtual const Jid & GetUser() = 0;
//! Provides different methods for credentials for login.
//! Takes ownership of this object; deletes when login is done
virtual XmppReturnStatus SetSaslHandler(SaslHandler * h) = 0;
//! Sets whether TLS will be used within the connection (default true).
virtual XmppReturnStatus SetTls(TlsOptions useTls) = 0;
//! Sets an alternate domain from which we allows TLS certificates.
//! This is for use in the case where a we want to allow a proxy to
//! serve up its own certificate rather than one owned by the underlying
//! domain.
virtual XmppReturnStatus SetTlsServer(const std::string & proxy_hostname,
const std::string & proxy_domain) = 0;
//! Gets whether TLS will be used within the connection.
virtual TlsOptions GetTls() = 0;
//! Sets the request resource name, if any (optional).
//! Note that the resource name may be overridden by the server; after
//! binding, the actual resource name is available as part of FullJid().
virtual XmppReturnStatus SetRequestedResource(const std::string& resource) = 0;
//! Gets the request resource name.
virtual const std::string & GetRequestedResource() = 0;
//! Sets language
virtual void SetLanguage(const std::string & lang) = 0;
// SESSION MANAGEMENT ---------------------------------------------------
//! Set callback for state changes.
virtual XmppReturnStatus SetSessionHandler(XmppSessionHandler* handler) = 0;
//! Initiates the XMPP connection.
//! After supplying connection settings, call this once to initiate,
//! (optionally) encrypt, authenticate, and bind the connection.
virtual XmppReturnStatus Connect() = 0;
//! The current engine state.
virtual State GetState() = 0;
//! Returns true if the connection is encrypted (under TLS)
virtual bool IsEncrypted() = 0;
//! The error code.
//! Consult this after XmppOutputHandler.OnClose().
virtual Error GetError(int *subcode) = 0;
//! The stream:error stanza, when the error is XmppEngine::ERROR_STREAM.
//! Notice the stanza returned is owned by the XmppEngine and
//! is deleted when the engine is destroyed.
virtual const XmlElement * GetStreamError() = 0;
//! Closes down the connection.
//! Sends CloseConnection to output, and disconnects and registered
//! session handlers. After Disconnect completes, it is guaranteed
//! that no further callbacks will be made.
virtual XmppReturnStatus Disconnect() = 0;
// APPLICATION USE -------------------------------------------------------
enum HandlerLevel {
HL_NONE = 0,
HL_PEEK, //!< Sees messages before all other processing; cannot abort
HL_SINGLE, //!< Watches for a single message, e.g., by id and sender
HL_SENDER, //!< Watches for a type of message from a specific sender
HL_TYPE, //!< Watches a type of message, e.g., all groupchat msgs
HL_ALL, //!< Watches all messages - gets last shot
HL_COUNT, //!< Count of handler levels
//! Adds a listener for session events.
//! Stanza delivery is chained to session handlers; the first to
//! return 'true' is the last to get each stanza.
virtual XmppReturnStatus AddStanzaHandler(XmppStanzaHandler* handler, HandlerLevel level = HL_PEEK) = 0;
//! Removes a listener for session events.
virtual XmppReturnStatus RemoveStanzaHandler(XmppStanzaHandler* handler) = 0;
//! Sends a stanza to the server.
virtual XmppReturnStatus SendStanza(const XmlElement * pelStanza) = 0;
//! Sends raw text to the server
virtual XmppReturnStatus SendRaw(const std::string & text) = 0;
//! Sends an iq to the server, and registers a callback for the result.
//! Returns the cookie passed to the result handler.
virtual XmppReturnStatus SendIq(const XmlElement* pelStanza,
XmppIqHandler* iq_handler,
XmppIqCookie* cookie) = 0;
//! Unregisters an iq callback handler given its cookie.
//! No callback will come to this handler after it's unregistered.
virtual XmppReturnStatus RemoveIqHandler(XmppIqCookie cookie,
XmppIqHandler** iq_handler) = 0;
//! Forms and sends an error in response to the given stanza.
//! Swaps to and from, sets type to "error", and adds error information
//! based on the passed code. Text is optional and may be STR_EMPTY.
virtual XmppReturnStatus SendStanzaError(const XmlElement * pelOriginal,
XmppStanzaError code,
const std::string & text) = 0;
//! The fullly bound JID.
//! This JID is only valid after binding has succeeded. If the value
//! is JID_NULL, the binding has not succeeded.
virtual const Jid & FullJid() = 0;
//! The next unused iq id for this connection.
//! Call this when building iq stanzas, to ensure that each iq
//! gets its own unique id.
virtual std::string NextId() = 0;
// Move these to a better location
#define XMPP_FAILED(x) \
( (x) == jingle_xmpp::XMPP_RETURN_OK ? false : true) \
#define XMPP_SUCCEEDED(x) \
( (x) == jingle_xmpp::XMPP_RETURN_OK ? true : false) \
#define IFR(x) \
do { \
xmpp_status = (x); \
if (XMPP_FAILED(xmpp_status)) { \
return xmpp_status; \
} \
} while (false) \
#define IFC(x) \
do { \
xmpp_status = (x); \
if (XMPP_FAILED(xmpp_status)) { \
goto Cleanup; \
} \
} while (false) \