/* * 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. */ #ifndef THIRD_PARTY_LIBJINGLE_XMPP_XMPP_XMPPENGINE_H_ #define THIRD_PARTY_LIBJINGLE_XMPP_XMPP_XMPPENGINE_H_ // 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 { XSE_BAD_REQUEST, XSE_CONFLICT, XSE_FEATURE_NOT_IMPLEMENTED, XSE_FORBIDDEN, XSE_GONE, XSE_INTERNAL_SERVER_ERROR, XSE_ITEM_NOT_FOUND, XSE_JID_MALFORMED, XSE_NOT_ACCEPTABLE, XSE_NOT_ALLOWED, XSE_PAYMENT_REQUIRED, XSE_RECIPIENT_UNAVAILABLE, XSE_REDIRECT, XSE_REGISTRATION_REQUIRED, XSE_SERVER_NOT_FOUND, XSE_SERVER_TIMEOUT, XSE_RESOURCE_CONSTRAINT, XSE_SERVICE_UNAVAILABLE, XSE_SUBSCRIPTION_REQUIRED, XSE_UNDEFINED_CONDITION, XSE_UNEXPECTED_REQUEST, }; // XmppReturnStatus // This is used by API functions to synchronously return status. enum XmppReturnStatus { XMPP_RETURN_OK, XMPP_RETURN_BADARGUMENT, XMPP_RETURN_BADSTATE, XMPP_RETURN_PENDING, XMPP_RETURN_UNEXPECTED, XMPP_RETURN_NOTYETIMPLEMENTED, }; // TlsOptions // This is used by API to identify TLS setting. enum TlsOptions { TLS_DISABLED, TLS_ENABLED, TLS_REQUIRED }; //! 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 { public: 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 { public: 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 { public: 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 { public: 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 { public: 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 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) \ #endif // THIRD_PARTY_LIBJINGLE_XMPP_XMPP_XMPPENGINE_H_